1. Provides support for multiple class drivers in a single file via the extended 'cfrg' resource. The following class drivers have been merged into the "USB Device Extension" file:
USBHubDriver0
USBHubDriver1
USBCompositeDriver
USBHIDKeyboardModule
USBHIDMouseModule
USBHIDUniversalModule
USBOpenHCIDriver
2. Have enabled the isoch bit for the 'usb ' Gestalt selector to indicate support for the USBIsochRead/Write calls. If your process depends on isochronous support, check first for the presence of USB v1.2. Your installer should check for the presence of USB v1.2 and alert the user to upgrade their System Software if this release is not present.
3. Support for Control endpoints other than endpoint 0.
4. New format for the USB Expert Log. Using the version of USB Prober supplied with the DDK, you can even change the status level to hide some status messages. At the default level, typically only errors are shown in the log.
5. Hub Driver now handles hub-removal properly (should not leave any pending transactions (which could cause crashes) when hubs are unplugged.
6. Hub Driver will refuse to match to any device that's not a USB Hub.
7. Create internal interface node before initializing class drivers. This allows a driver's interfaceInitializeProc to call GetDriverConnectionID for it's interfaceRef.
8. Changed USB mouse module to always shutdown gracefully when unplugged. It could potentially hang around forever in some cases.
9. Fixed bug where the interrupt polling rate was never less than 4 ms for high-speed devices.
10. Fixed De/Allocmem to return the correct "kUSBPending" status.
11. Version Information added to "USB Device Extension".
12. New Version of USB Prober now supports PageUp/PageDown keys.
13. Fixed a USB v1.2d3 driver matching problem in the USB Expert that was mis-matching the Kodak DC 220/260 cameras to the QuickCam driver. Also the Umax scanner & Peracom serial adapter were matching to the hub driver! This problem was only in USB v1.2d3.
14. Added HID Notification method to allow all boot protocol data to be retrieved for keyboard/mouse. This new method is demonstrated in the updated driver samples for the mouse and keyboard.
15. Updated the Composite driver to indicate how much power was available in the expert log, when there was not enough power available.
16. Fixed a bug that would cause a 10 second delay if there were no USB UIMs loaded.
17. Remove USB Expert Log error message about string index = 0, this means no string is available and is not an error.
18. Fixed problem where some devices would generate a false "Not Enough Power" dialog.
19. Put manufacturer, product, and serial number string in name registry.
20. Added re-entrancy protection for all UIM calls. This should address developer-discovered problems where stressing the USB software would result in USBBulkRead returning -1 errors, or USB stopping all together.
21. Changed Keyboard & Mouse drivers to use "SetIdle" for non-Apple keyboards & mice. This should improve compatibility with some devices that fail to report key-ups except when SetIdle is used.
22. Fix USBResetPipeByReference to always allow the data-toggle to be reset in the hardware (as documented).
23. Fix usbActCount which was being returned incorrectly when it was 32k less than usbReqCount.
24. Fixed USBFatalError to once again show the Pascal-string that is passed in. We recently got it to show the string, but we were treating it as a C-string instead of the documented Pascal-string.
25. The mouse driver notification "cancel" call now clears the notificationRefCon, instead of (incorrectly) the interruptRefCon. This problem was introduced in an earlier version of USB 1.2
26. Secondary interrupts are used to serialize access to the UIM (this should have the effect of fixing random crashes with mass storage devices and scanners).
27. Fixed isoch error returns.
28. Short packets now terminate a large read request properly.
29. The last frame of an isoch write request was sometimes longer than submitted.
30. Modified USB so that only selected levels of Expert messages are displayed. By default only level 1 - 3 Expert Status messages are displayed. Messages passed using the USBExpertStatus call are level 4 messages and are not displayed unless the status level is change to 4 or 5.
31. Fixed USBIsocRead to return the correct frActCount value.
32. Fixed the incorrect error results for the USBIsocRead call that were introduced in USB v1.2f4.
Changes from USB v1.0/v1.0.1 -> v1.1
------------------------------------
The following changes were made for USB 1.1
1. USB v1.1 can support more than one USB Controller. If you are looking in the name registry, you need to look under every USB controller node for hubs and devices that may be attached.
2. Using Isochronous transfers. Version v1.1 contains support for Isochronous transfers. You can test for the presence of Isochronous support by checking the gestalt selector gestaltUSBAttr (‘usb ‘). If gestaltUSBHasIsoch (bit 1 = 0x02) is set, then Isochronous support is available in the form of two new calls:
OSStatus USBIsocWrite(USBPB *pb);
OSStatus USBIsocRead(USBPB *pb);
Refer to the Mac OS USB API Reference Guide included with this DDK for information on implementing isochronous support.
NOTE: The gestalt bit, gestaltUSBHasIsoch, was not set for versions of the 1.1 DDK before
1.1a4, even though the above mentioned calls were present. For releases of USB >= v1.1a4, this bit is set correctly.
3. USB v1.1 improves upon the bus enumeration at startup, and attempts to load drivers before other system extensions. It does this by providing task time for the USB expert to process all hub communications. When all hubs have reported that they they have discovered their devices, and we’ve searched for class drivers, then the remainder of the booting process (loading extensions and launching the finder) continues.
4. Support for System Sleep. Additional driver messages have been defined for handling sleep/wake within the MacOS. Under USB v1.1 class drivers are notified through their USBDriverNotifyProcPtr with the following messages:
kNotifyUSBSystemSleepRequest
kNotifyUSBSystemSleepDemand
These messages correspond to the SleepXXXX messages defined in the PowerManager (Inside Macintosh: Devices, chapter 6). Your driver can return any value appropriate to these messages (ie, to deny a SleepRequest, return a non-zero value).
5. Starting with USB vers 1.1a4, there is a new "locationID" property found in the name registry node of each USB device. This property contains a 32-bit number that is unique across all USB devices found in the system. It will remain the same accross reboots (and unplugs/re-plugs) for a
particular device as long as it is plugging into the same port in the USB device tree. To find the name registry entry for a particular device, you can look for the property "deviceRef" with the value equal to your deviceRef. Once you have found the NameRegistry node, you can check for
the value of the "locationID" property.
6. USBResetDevice(USBPB *PB); - A new USB function that will reset a device as specified by USBReference. If there are any outstanding USB parameter block calls on open pipes or interfaces associated with the device, these calls will complete with an error.
7. USBOpenDevice & USBConfigureInterface now kill/close interface/pipes if performed on an already open interface or device. As with USBResetDevice, if there are any outstanding USB parameter block calls on open pipes or interfaces, these calls will complete with an error.
8. Added USBToHostLong and HostToUSBLong functions.
9. USBOpenDevice now checks if the configuration requested requires more power than is available. This call returns a failure code and puts up an error dialog if there is not enough power. To keep the dialog from being displayed, make sure that the desired configuration specified in the usb.cntl.WValue field is within the power limits passed to the class driver in the Driver/InterfaceInit call.
9a. USB v1.1 catches illegal power configurations. USB raises an alert and returns an error if any driver tries to configure a device which needs more power than is available. USB provides a mechanism for the class driver to detect this problem using the USBFIndNextInterface call. The USBFIndNextInterface API is changed so that you can pass in the power available in the usbReqCount field of the USB parameter block.
10. Improved the reliability of Bulk, Interrupt, and Isochronous transfers.
11. Added "addressed" endpoint/interface functionality. Use the kUSBAddressRequest flag when passing in an endpoint/interface number. For example, when making some USBDeviceRequest calls, the WIndex field must be set to an endpoint or interface number to identify the recipient of the call. USB v1.1 simplifies the need to set this value. USB v1.1 checks if the usbFlags field has the kUSBAddressRequest bit set, and if so further checks the usb.cntl.BMRequestType field to determine what endpointNumber needs to be set in the usb.cntl.WIndex field.
12. Fixed the USBDelay call so that it now honors the kUSBTaskTimeFlag bit.
13. Fixed USBFindNextInterface to return kUSBNotFound if the specified interface does not exist.
14. Improved bus enumeration so that most USB devices which are present at system startup will be enumerated before INITs are executed.
15. Changed the method by which Mac OS USB reads the device descriptor to use the method defined in the USB 1.1 specification. This means that the first 8 bytes of the descriptor are read, then the entire descriptor is read.
16. Implemented "Captive device" support. This provides a fix for some compound devices that have 4 built-in ports and a captive device (ie. a keyboard with a built in hub that has 4 ports). This is per the USB 1.1 specification (not the Apple Mac OS v.1.1 spec).
17. Fixed a problem where some 3rd party keyboards didn't set the LEDs correctly, or 3rd party mice did not work correctly.
18. Updated USBProber - Fixed a problem where incorrect ProbeEndPoint messages were sometimes seen. USBProber now displays (again) the root hub info.
19. The root hub driver was updated and the product ID has changed. As a reminder, you should never 1. talk to the root hub directly, 2. replace the hub drivers, and 3. depend on the root hub product ID staying the same from release to release.
20. Fixed USBGetNextDeviceByClass so that it correctly iterates through all devices present, including Composite class devices.
21. DeviceNotifications are sent for matching devices already connected when the USBInstallDeviceNotification call is made. When a client registers to receive device notifications, any existing devices are reported immediately.
22. Fixed bug that caused immediate errors to be returned incorrectly. This causes problems when drivers requested transfer that could not be accomodated, they would never get a callback indicating the transfer completed.
23. Implemented Composite class driver replacement, to allow vendor-specific composite drivers to be re-loaded if attached at boot. This change makes all devices attached at boot look like they have been hot plugged.
24. Added capability for more than one driver to be tried for a given device. Now drivers can return an error from the validateHWProc and USB will search for another driver match.
25. Fixed problem that produced "pipeStalled" errors after devices had been unplugged/replugged 15 times or so.
26. Fixed a problem where if a mouse were removed while it's button was down, the system would be frozen and could not recover.
27. Fixed a bug that caused more than one mouse attached to an iMac to get a "sticky" button sometimes.
28. Improved hub hot plug/unplug robustness.
29. Fixed problem that prevented "perfect" match when deviceRevision match was exact.
30. Fixed USBGetDeviceDescriptor to return the correct descriptor length value.
31. Fixed DeviceNotification to identify whether an interface or device driver is being added.
32. Fixed problem that was making the mouse non-functional after quiting from Quake game.
33. Fixed problem where high-powered devices (such as QuickCam) would not report insufficient power when connected to a bus-powered hub. Now they do!
34. Fixed problem that would freeze the mouse when unplugging the keyboard while any Office98 app was running.
35. Fixed problem where a USB class driver could receive two callbacks when an error occurred, and they attempted to abort any other transactions.
API Changes from USB v1.0/v1.0.1 -> v1.1
----------------------------------------
The following API changes were made for v1.1 and WILL affect the compilation of your program.
1. The USBPB structure has been changed to support Isochronous parameter blocks. The USB Parameter Block (USBPB) has been converted into a unions to support Isochronous transfers. The change is binary compatible with previous USB releases (can keep the same kUSBCurrentVersion value), however you will need to modify your source code in order to use the USB.h header file that is supplied with the Mac OS USB v1.1 DDK.
The update can typically be made with a search/replace of the following strings:
Old New
usbBMRequestType usb.cntl.BMRequestType
usbBRequest usb.cntl.BRequest
usbWValue usb.cntl.WValue
usbWIndex usb.cntl.WIndex
To aid in this conversion, macros with these substitutions are available in USB.h, just define OLDUSBNAMES before including <USB.h> We recommend changing your source code soon as possible, as these macros will disappear in the future.
2. There has been a change to the USBClassDriverPluginDispatchTable. The USBDDriverNotifyProcPtr is prototyped as
If the version of the USBClassDriverPluginDispatchTable is set to kUSBClassDriverPluginVersion, (used from the v1.1 USB.h header file) then the USBDriverNotifyProcPtr has the prototype described above. Note that drivers that were compiled with an earlier version of the USB.h header file will have a different kUSBClassDriverPluginVersion value and the USB Manager will call the DriverNotifyProc without the refcon parameter.
USB 1.1 Compatibility with USB 1.0.1
------------------------------------
You can build your USB compatible products using the USB v1.1 components and run them under a USB v1.0 or v1.0.1 environment so long as you follow these caveats -
1. When your USBDriverNotifyProcPtr routine is called, check the version of USB that is present before using the refcon parameter. For USB v1.0 and v1.0.1, the refcon parameter is invalid.
2. For all versions of USB, check that there is isochronous support before making the USBIsochRead/Write calls. Your class driver must also weak link with the USBServicesLib file. If the driver makes the USBIsocRead/Write calls and hard links with the USBServicesLib file, then the system will check for the support of these calls, find that they are not available and not allow the driver to load.
3. Keep in mind that for v1.0 and v1.0.1, there are known problems which are not fixed simply by building the product with the USB v1.1 headers and libraries. These problems are referenced in this readme file. Some of these issues are discussed in more detail on the USB Developer Alerts web page. The URL to this page is as follows:
1. Implemented a fix to the USBModem example, file ShimSerialHAL.c, HAL_ShimInput routine to correctly handle incoming parameter block data processing.
Changes from USB v1.0 -> v1.0.1
-------------------------------
The following changes were made for USB 1.0.1
1. USB.h
- Removed the call USBGetConnectionIDByClass as its usefulness is limited. Use the USBGetNextDeviceByClass call instead so that you can interate through the available devices.
- Added a number of Hub Defines that were previously in a private interface file.
2. Addressed the following bugs
- Fixed several USBBulkRead issues which includes the lost print band problem.
- UIM buffer alignment fix. The UIM (USBOpenHCIDriver) could cause a class driver to receive a -6908 error if the buffer passed in was not aligned on a "MaxPacketSized" boundary. We have sent out information on how to workaround this to developers, this fix will remove this restriction. This problem can only occur when reading from BULK devices.
- Device stall could return improper value in the usbActCount field. This could make it impossible for drivers to attempt to recover from a pipe stall error.
- Workaround for potential data corruption with some OHCI controllers. This problem shows up as corruption in transmitted high-speed data, following a low-speed input data transfer.
- Fixed problem with USB Services replacement that causes a crash after the "No Software" dialog is displayed in the case where there is a "USBFamilyExpert" extension in the system folder.
-
Hub attach delay. We now wait, as per the USB Specification, the required 100ms after a new device is attached to the hub before configuring it. This should improve hot-plugging of devices (especially if sometimes they aren't detected).
- Improved driver matching for compatibility shims. The shims were matching on info from the driver, not info from the device. This could cause some drivers not to be found by a shim.
- Make sure ClassDrivers are locked to prevent VirtualMemory paging. This could potentially fix crashing problems on very busy systems.
- Increased idle-queue size to 96. We could potentially overflow this queue (and have things stop working) if there were too many devices attached.
- Fixed several incorrect error returns in the PipeState functions.
- Fixed problem where a legal minimum config descriptor (a single configuration and interface) cause and error when attempting to find the interface.
- Zero length transactions are allowed on the bus.
- USL and UIM have to agree on a version number to work together. This stops unmatched interfaces causing problems.
Changes/Additions to the USB v1.0.1 DDK
---------------------------------------
1. Include the correct UniversalHIDModule class driver for use with Game Sprockets v1.3. Game Sprocket supported devices now work properly on systems which use the Extension-based USB.
2. Updated the PrinterClassSample so that the it fixes the 68K structure alignment problem. Also modified the code so that the DRVR and NameRegistry items are removed, when the class module unloads.
